COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	CKSUM lets you "keep track" of E-format files, in the sense that when they
C00014 ENDMK
C⊗;
CKSUM lets you "keep track" of E-format files, in the sense that when they
change it will tell you which pages the changes are on.  Two typical
applications would be (1) a large source file, where you don't want to sit
through the ATSIGN program just to learn which sections have changed, and
(2) the BBOARD and GRIPES files, where you might not want to scan the E
directory for changes and/or want to find out where some loser added a
comment without doing an NDBBOARD command to update the directory line.

CKSUM operates by computing a 36-bit checksum (not a straight longitudinal
checksum) for each page of the file, not counting the directory page.  The
file MUST be in E format -- in particular, pages must start on record
boundaries.  The checksums, along with the date and time the file was last
written, are kept in the file CKSUM.DAT on your master ([1,xxx]) account.
(If you don't have a [1,xxx] account, you lose.  Create one.)  One
CKSUM.DAT file may contain data for any number of checksummed files.  You
can ask about changes in any or all of the files in one run of CKSUM.

When reporting changes, CKSUM does its best to figure out what has actually
happened to the file.  If pages have moved around without being changed, it
reports where they have moved to.  If pages have been deleted or added with
no other changes occurring, it reports that.  But if deletions or additions
occur together with other changes, CKSUM has no way of knowing which pages
were deleted/added and which changed; in this case it reports the change in
the total number of pages and says which pages in the new file fail to
match any in the old one.

To use CKSUM, the general format is:

.R CKSUM;{files}{switch}

(If both "files" and "switch" are omitted, the semicolon is unnecessary.)
The optional "files" field is a list of file names, separated by commas.
Filehacks (e.g., \M) ARE recognised, but the partial-sign construct is NOT.
Down-arrows may be used to quote odd characters as usual.  If no list of
files is given, then the default is to operate on all the files in
CKSUM.DAT; otherwise, only the files named will be used and any not yet in
CKSUM.DAT will be added to it.  (You'll be asked to confirm adding new
files, as a hedge against typoes.)  If CKSUM.DAT does not yet exist, you'll
be asked to confirm initialising, and if you did not give a list of files
you'll be asked again for one; typing a null line to this request gets you
a default of BBOARD and GRIPES.

No more than one switch is allowed.  The available switches are:

/DELETE	    delete (selected) entries from CKSUM.DAT; you'll be asked
	    to confirm this.
/LIST	    just list (selected) files in CKSUM.DAT, together with the
	    date and time of the last checksummed version, and the
	    number of pages in each.
/READONLY   report changes as usual, but don't store the new checksums
	    in CKSUM.DAT (normal operation is to store the new checksums
	    so that you only hear of each change once).
/WRITE	    override automatic /READONLY for file classes (see below).

Switches may be abbreviated to single letters.  If any switch except /W
is present, then any new files in the "files" parameter are reported and
ignored, since /D, /L, and /R all imply that nothing is to be added to
CKSUM.DAT.  Also, a null "files" parameter is forbidden with the /D switch
-- if you really want to do that, just delete CKSUM.DAT.  (It's kept
delete-protected as a precaution, but you can of course override that.)

After CKSUM has exited, if it reported any new or altered pages (as opposed
to just deleted pages and unchanged files), you can type CONTINUE and CKSUM
will swap to E with the file stack containing the file(s) with new/altered
pages and each file having a "mark" placed at the top of each such page.
Thus you can then use αM commands to look at pages until you come back to
one you've already seen, then use α+αH to get to the next file, etc.
Note that this destroys the tmpcor file used by E to remember the last few
files you edited prior to running CKSUM.

CKSUM also lets you specify up to 27 "classes" of files, identified by the
letters A through Z and the digit 0.  By default, all files start out in
class 0.  A file which is in a class other than 0 is automatically treated
as /READONLY; that is, changes to the file will be reported but the new
checksums will not be saved.  This lets you keep track of the cumulative
changes to some files while looking at day-to-day changes in others.  You
can force CKSUM to save the new checksums for these files by giving the
/WRITE switch.  To change the class a file is in, include in the {files}
parameter the file name followed by =X where X is the class to put it in.
thus  R CKSUM;\BBOARD=X,\GRIPES=Y  puts the BBOARD file in class X and the
GRIPES file in class Y.  When you specify a class for a file, that file
will not be checksummed during that particular run of CKSUM.  (If you also
include files in the {files} list without any "=" specification, those
files will be checksummed as usual, or listed or deleted depending on the
/L and /D switches.)  Finally, you can use classes in place of file names.
A list of one or more file classes enclosed in parentheses is equivalent
to listing all the files in those classes.  Thus, after the above class-
setting example,  R CKSUM;(XY)  would show changes to BBOARD and GRIPES
(but would not save the new checksums),  R CKSUM;(X)/W  would show changes
to BBOARD and WOULD save the new checksums for it, and, to take a somewhat
bizarre example just to show some of the interactions going on (in case
someone tries it and wonders what's happened),  R CKSUM;(X)=0,FOO=0,(0)/D
would change BBOARD to be in class 0, would leave FOO alone (assuming it
were already in the checksum file, it would have defaulted to class 0),
and would delete all other files from the checksum file except for GRIPES.
GRIPES is spared because it's not in class 0, and BBOARD and FOO are
spared because they were given class specifications in the command line.
One last note regarding classes: the /L output includes the file class
in parentheses for all files listed that are not in class 0.

Note: CKSUM does not bother recomputing checksums unless the file in
question has been changed (based on date/time last written), so it should
be moderately fast when there's nothing to report.  If the only change has
been an invisible one like updating the E directory (via E's αXUPDATE
command) without changing any other pages, or "burping" one or more pages,
CKSUM will report that the file has been edited with no visible effect.

If you ask to checksum a file that lacks a valid E directory, CKSUM will
complain, but it will still compute the checksums for any pages (other than
page 1) which happen to start on record boundaries.  Thus, in particular,
if you checksum a one-page file, you will be informed thereafter whenever
the file is edited, even though CKSUM will be unable to find any differences.

Comments, suggestions, bugs, etc., via GRIPE CKSUM.